Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Include doc and manpage in Debian package. #112

Open
wants to merge 4 commits into
base: master
Choose a base branch
from

Conversation

fidergo-stephane-gourichon

@ssokolow this follows your request on #106 .

How about some credits in the documentation?

Hints from git history. What do you think?

git log --pretty=%an | sort | uniq -c | sort -nr

    376 Stephan Sokolow
     12 Stéphane Gourichon
      3 Yuting Xiao
      3 Justin
      2 wmax
      1 soaxelbrooke
      1 Valentin Agachi
      1 Valdis Vitolins
      1 Oliver Gerlich
      1 Matthias Putz
      1 David Stygstra

@coveralls
Copy link

coveralls commented Feb 9, 2020

Coverage Status

Coverage remained the same at 61.029% when pulling b507d53 on fidergo-stephane-gourichon:feature_debian_package into a0098e4 on ssokolow:master.

@ssokolow
Copy link
Owner

ssokolow commented Feb 9, 2020

I've been meaning to go through and put together an AUTHORS file for the repository as a whole (which would also go in /usr/share/docs/). Thanks for reminding me.

There is already one for the docs at docs/AUTHORS since the docs were much simpler. (Just me, David Stygstra for the first bunch of illustrations, and the usual attributions for any icons and other bits I used.)

I'm on a bit of an odd schedule right now and need to get to sleep, but, tomorrow, I'll start looking into what the best way is to reconcile the convention of having an AUTHORS file with also having that information in the docs.

(Maybe I could put together something which runs Sphinx's make text on just a single authors.rst page and stores the output as AUTHORS in the repository root. Then I could add instructions relating to it in the developer's guide section of the manual.)

ssokolow pushed a commit that referenced this pull request Feb 10, 2020
Add...
- A unified "Authors" page at the end of the HTML manual
- An AUTHORS file in the root of the project
- A script to generate AUTHORS from the ReST sources
- A section on AUTHORS in the developer's guide
- An "et al" to the site footer that should have been there since
  the beginning

(Thanks to PR #112 for reminding me to do this.)
@ssokolow
Copy link
Owner

ssokolow commented Feb 10, 2020

Done.

That AUTHORS file can now be added to the Debian packaging so that there's something in /usr/share/doc that doesn't require an HTML parser to display.

(The HTML version needed to be authors/index.html rather than authors.html to work around limitations in what subset of a document Sphinx can be induced to render in isolation for text output.)

@ssokolow
Copy link
Owner

ssokolow commented Feb 10, 2020

Oops. Almost forgot about a couple of credits for people whose names don't show up in git log. (Only in docstrings and code comments.)

Fixed.

This implies building HTML doc and therefore
adds python3-sphinx as a build-time dependency.
@fidergo-stephane-gourichon
Copy link
Author

Great! I rebased the branch of the PR.

What version number do you want? I guess 0.4.0gtk3 is no longer relevant. 0.4.0? 0.4.1?

@ssokolow
Copy link
Owner

ssokolow commented Feb 11, 2020

In the short term, I'd prefer whatever this command outputs so the package name agrees with setup.py and anything else in QuickTile that reports its version:

./setup.py --version

(I haven't bumped it from 0.4.0 to 0.4.1 yet because there have been no changes to the code yet... just to the site/documentation.)

In the long term, I'll want to try to reduce the amount of changelog duplication too.

@fidergo-stephane-gourichon
Copy link
Author

In the short term, I'd prefer whatever this command outputs so the package name agrees with setup.py and anything else in QuickTile that reports its version:

Makes sense.
It currently returns 0.4, not 0.4.0. But the ChangeLog says 0.4.0.
So I guess it's what you want for the formal Debian package number.

In the long term, I'll want to try to reduce the amount of changelog duplication too.

Agreed. DRY principle. Some projects maintain a "short" changelog, concise, no details, and a "long" changelog. Git history feels like a long changelog anyway.

@ssokolow
Copy link
Owner

Makes sense.
It currently returns 0.4, not 0.4.0. But the ChangeLog says 0.4.0.
So I guess it's what you want for the formal Debian package number.

The first thing I'd want to do is check whether there's a Debian policy on the matter before making a decision, then let that inform my decision on which choice to unify both on.

Agreed. DRY principle. Some projects maintain a "short" changelog, concise, no details, and a "long" changelog. Git history feels like a long changelog anyway.

My git history would be a very long changelog, so definitely not that. I was thinking more of how to minimize duplication between the ChangeLog file and the Debian changelog.

Copy link
Owner

@ssokolow ssokolow left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are a couple of things that look questionable to me, but thanks for the work. I've been meaning to get back to work on QuickTile but I've been bogged down preparing the house for winter for a while.

(And, prior to that, the year has just been a mess for me. I didn't start to get productive on non-essentials until two months ago.)


EOF

set -euo pipefail

cd "$(dirname "$(readlink -f "$0")" )"
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you have a specific example of why this change is necessary?

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ugh. I'm not used to GitHub's reviews. I'll have to remember to mark the last line rather than the first next time.

bash recompile_local_debian_package.sh --install-deps-only
USER=$(id -un) ; userdel \"\$USER\"
GID=$(id -g) ; groupadd -f -g \$GID $(id -gn)
useradd -u $(id -u) --gid stephane -l -m \"\$USER\" -s /bin/bash
Copy link
Owner

@ssokolow ssokolow Nov 19, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You may be stephane, but I'm ssokolow and have no such user and group on my system. It looks like you're either missing username and group lookups here or should use names that make it more clear that all that matters is matching the external UID and GID.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oops! Of course this is unacceptable for published software. Probably a local expedient that I forgot to refine.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants